
BibTeX Help


                                           help version: 4.1
                                                created: 08/17/94 {02:18:07 pm}
                                            last update: 03/06/01 {01:59:09 pm}

	  	Introduction


This document describes features of Bib mode and the BibTeX menu, which
were written to simplify the use and maintenance of BibTeX citation
database files.

Bib mode is entered when you open a file with a '.bib' suffix, or when you
select the mode explicitly from the modes menu.  In Bib mode,


   A BibTeX menu is added to the menubar.  Menu items summarized below.

   Selecting Mark File in the Marks menu (M on the sidebar), will
    add an index mark for the cite-key of each entry in the bib file.

    Marks are added in order of appearance in the file.  To order them
    alphabetically, use the "Sort Marks --> Alphabetically" command in
    the Bibtex menu.

   Keywords in Bib files are automatically colorized.

   Double-clicking on an abbreviation string with the command key held
    down (command-double-clicking) will move the cursor to the definition
    of that abbreviation.

   Command-double-clicking on the cite-key of a crossref field will
    move the cursor to the referenced entry.


A "BibTeX Example.bib" file is available for exploring the features of the
mode and menu.  You can modify this file as much as you like, reformat,
experiment with completions, etc.

The most recent changes to the mode include

   More options for the BibTeX menu for faster building.
   Validation is now possible for single entries or an entire file.
    Validating will report missing required and "non-standard" fields.
   Duplicate cite-keys can be found in the current window and across files.
   Default entry fields can now be defined through BibTeX menu.
   The list of all recognized bibliography files can be reviewed.
   One can rapidly search for text in any field in these files.
   Added support for indices and databases through the Bibtex menu.

   Colors can now be changed through Mode Preferences dialog.
   Comment menu items are enabled.
   Smart quotes, dots from TeX mode now available as optional preference.
   Field insertion now available as an electric completion.
   Colorization and Completion support for select LaTeX commands.
   User defined acronyms can be expanded using the Expansion key.
   Completions Tutorial is now available under "Config --> Mode Prefs".
   .bib conversion packages now available under the Conversions menu.


	======================================================================


Alpha's Bib mode has been designed with three major tasks in mind.  First,
the mode helps you create .bib files.  Its entry templates are completely
customizable, and (by using electric completions) can generally be inserted
with only three or four keystrokes.  Commonly used strings (such as
addresses, publishers, etc) can be defined as Bib mode specific acronyms
and expanded using Alpha's "expansion" key.  

The Navigation menu items allow you to easily move through a document, and
the Marks menu and "Index This Window" menu item provide concise summaries
of the entries in the current window.  The Formatting menu includes items
that clean up the current window and validate entries to ensure that they
include the required fields.  The Cite Key Lists menu contains some items 
that help ensure that you do not have duplicate cite-keys in the file.

Second, Bib mode complements Alpha's TeX mode for inserting citation keys 
from a .bib file into a LaTeX document.  By creating a bibliographic Index 
or Database, citations can be entered as electric completions.  Command 
double-clicking on a citation within a LaTeX document will take you to its 
original entry -- opening the .bib file if necessary.

Finally, the mode allows your collection of .bib files to be used as a
searchable database.  Searches can be limited to the current open window,
or expanded to include all of the .bib files recognized by Alpha.  Searches
can be limited to specific fields, or to entire entries.  The results of a
search can be optionally appended to previous search windows, and these
search windows themselves can be searched to narrow the results.  In any
"Search Results" window, command double-clicking on an entry will take you
to its original definition.  All searches support regular expressions as
well as alpha-numeric text.


	  	BibTeX menu


Here's a description of the commands available from the BibTeX menu.  Note
that the menu can be made hierarchical (for those with smaller monitors) by
toggling the "Hierarchical Menu" item in the "Bib Mode Options" menu. 
Otherwise some items are dynamic, only available by holding down the
command key while accessing the menu.

The preference "Short Bib Menu" determines if the Search, Cite Key Lists,
Bibtex Conversions, or Bib Mode Acronyms will be included in the menu.  (If 
not, any key-bindings for the items will still work.)

The preference "Database Menu Items" determines if the "BibTeX File List",
"Bib Mode Files" and "Database" menus/menu items are included in the main 
Bib menu.

Unsetting either one of these preferences will result in a faster start-up 
time when Bib mode is initially called.  They can both be set/unset using 
the "Bib Mode Options" menu described below.


	BibTeX Application

Switch to the BibTeX application (launching it if necessary).


	BibTeX Home Page

Open the "Home Page" url set in the "Config --> Mode Prefs --> Preferences"
dialog.  The default setting is to Vince Darley's Macintosh port of the 
BibTeX application, but this url can be set to any page that you find you 
use a lot when editing .bib files.  (For example, as a sociologist I often 
find myself using a Social Sciences Citation Index web site to lift 
article or book abstracts.)


	  	 	BibTeX File List


This menu contains a list of all of the .bib files currently recognized by
Bib mode.  Selecting any will open it in a new window.  The "BibTeX Files"
menu described below allows you to set some preferences regarding how this
list is built.  Note that unlike the filesets menu, this list can be rebuilt
every time Alpha is restarted, and should only contain files that actually
exist.  (If you find yourself editing a lot of .bib files when you use 
Alpha, you could make this a global menu and have access to these files 
every time that Alpha is launched.)

When the Bib menu is first built, the file list will always be empty unless
the preference for "Build Files On Start" is set, but it can be easily
rebuilt using the "BibTeX File List --> Rebuild File List" menu item.  This
item will also recreate the menu should you find it necessary, but unless
you have deleted files during your editing session it should be remain
accurate.  This is also the list that would be used in Index and Database
creation, described in more detail below.

If the "Full Pathnames" preference is not set, then only the file names 
(without their parent directories) appear in the menu and in most list-pick 
dialogs.  

Tip: Holding down the "option" key while clicking on the title bar will
present you with a list of all currently recognized BibTeX files, as well
as all currently open windows.  Selecting any of these files or windows
will bring them to the front, opening them if necessary.  In Mac OS 8.0 and
above, option-clicking on the sides of the current window will present this
list as well, which means that you can simply move the mouse to the far
left of your screen and option or command click to pop up the menu.

	Open All Bib Files

Opens all of the files currently listed in the menu.  (It might be a good
idea to "List All Files" before using this to be sure that the list is up
to date.)  This can be a handy way to create an actual file set for all of
your bibliographies, using the "Create fileset from open windows" option.

	Close All Bib Files

Closes all of the .bib files currently listed in the menu.  If any of these 
files have unsaved changes, you will be prompted to save them first.


	  	 	Template insertion


	Entries

Insert a template for any of the various BibTeX bibliography entry types
(as in Tex mode).  By default, only the required fields an the entry are
included.

Tip: Hold down any modifier key while selecting an entry menu item to edit
its default fields, or use the "Default Entry Fields --> Entry Name" menu
items.

Choosing "Custom Entry" lets you pick the fields to be included from a list
of all fields -- you will also be given the option to save this as a
default entry, which will then appear in the menu and become available as
an electric completion.  Custom entries defined using this menu item
CANNOT, however, be properly validated.  See the "Adding New Entries"
section below for instructions on teaching Bib mode new entries for field
validation.

	Fields

Insert a template for any of the various BibTeX bibliography data fields.

Tip: Hold down any modifier key while selecting a field menu item to edit
the "Add Fields" preference.

Choosing Custom Field allows you to define your own field, which can then
be saved and inserted into the menu, and be made available as an electric
completion.

Choosing Multiple Fields lets you pick a number of fields to be included at
once.


	  	 	Entry Navigation, etc.


	Next Entry

Jump to the top of the next entry.

	Prev Entry

Jump to the top of the previous entry.

These items are also bound to <control>-<shift>-<arrow keys>.  The up and 
down arrows will simply move the cursor to the start of the next/prev entry.
Right and left arrows will also place this entry at the top of the window.

These items are also bound to 1 and 3 on the keypad when numlock is turned 
off.  These key bindings will place the next/prev entry in the center of 
the window.  The numlock in Alpha is toggled by holding down the shift key 
when pressing "num-lock" on the keypad.

If any text is currently highlighted, all of these navigation items will 
extend the current selection to the next/previous entry.

	Copy Cite Key

Copy the cite key for the current entry to the clipboard.

	Select Entry

Highlight the current entry (in which the cursor sits), allowing the entry
to be easily moved, copied or deleted.


	  	 	Formatting, Validating


	Format Entry

Reformat the current entry in a standard form, with data fields indented
and aligned, and data-field delimiters made uniform.  Afterwards, Alpha
jumps forward to the next entry, so you can keep hitting Ctl-Shift-L to
reformat a number of entries in a row.

The format may be customized via the Mode Preferences, such as aligning
equals signs, zapping empty fields, the style of braces to use ...  These
items are also available as toggleable menu items in "BibTeX Mode Options."

Fields which consist solely of defined strings, valid crossrefs, and
standard abbreviations (defined via the "Config --> Mode Prefs" dialog)
will not be surrounded by any delimiter during reformatting.

Tip: Command double-click on any valid field to format the entire entry.
This will place that entry at the top of the file, and your mouse should 
now be located somewhere within the next set of fields to format the next 
entry.

	Validate Entry

Evaluate the fields of the current entry to check for required fields, as
well as non-standard fields.  To ignore any "non-standard" fields contained
in entries, i.e. those which are neither required nor optional, toggle the
"Ignore Extra Fields" preference in the BibTeX Mode Options menu.

Note that only the "default" entries defined by Bib mode have information
regarding required versus optional fields.  Entries created using the
"Custom Entry" menu item cannot be validated.  To teach Bib mode new
entries for validation purposes, see the "Adding New Entries" section
below.

Tip: Command double-click on any valid entry name to validate the entire
entry.  This will place that entry at the top of the file, and your mouse
should now be located somewhere near the name of the next entry to validate
it.

	Format All Entries

(A dynamic menu item available by pressing the command key.)

Reformat the current entry and all subsequent entries to end of the file. 
You must go to the top of the window first to truly format "all" entries. 
If any entry cannot be formatted, results will be displayed in a new
window.

You can interrupt this by hitting the Cmd-. key

	Validate All Entries

(A dynamic menu item available by pressing the command key.)

Evaluate the fields for current entry and all subsequent entries to end of
the file, and check for duplicate cite-keys.  You must go to the top of the
window first to truly validate "all" entries.  Results will be displayed in
a new window if there were any missing fields, duplicate cite-keys,
unrecognized entries, or (optionally) any "non-standard" fields present.
Because this "results" window can get quite busy, all entries that simply
have missing fields will be listed in the marks menu.

You can interrupt this by hitting the Cmd-. key


	  	 	Searching


Bib mode offers several different ways to search the entries contained not
only in the current window but also within all of the files recognized by
Alpha as .bib files.

The first three items, searching Entries, Fields, and Bib Files, will
display their results in a "Search Results" window, with all unique
cite-keys listed in the Marks menu.  Command double-clicking on any
cite-key will jump to its original entry, opening the file if necessary. 
Additional searches can be appended to any current results window, or
displayed in a new one.  Results windows can be saved as files as well.

If a search of "All Bib Files" results in multiple files identified, you
will be given the option to insert the results of any listed file into the
results window.  Alternatively, you could list all matches in a "browser"
window, from which you can jump to any given match.

Note that "Search Results" windows themselves can be searched, to narrow
the selections.  (When doing so be sure to save the original window,
because this will be the only one containing the names of the source
files.)  Search windows can also be validated, checked for duplicate
cite-keys, or the entries could be counted, or the window could be sorted
and indexed ...

All of these searches can take regular expressions.

	Search Entries

Search for entries that contain a given alpha-numeric text string (i.e. no
dashes or other special symbols) or a regular expression.  Search strings
are not case-sensitive.

An example: Open the "BibTeX Example.bib" file.  Select "Search Entries",
and enter the search string "unix".  The results will be displayed in a new
window -- command double-clicking on any cite-key will send you to its
original location.  Now search for the string "C\+\+" -- the backslashes
are necessary because -'s and +'s are special regular expression symbols.

Tip: holding down the control key while command double-clicking on any text
will start a search for that text across all fields in the current window.

	Search Fields

(A dynamic menu item available by pressing the command key.)

Search for entries in which a particular field matches alpha-numeric text
(i.e. no dashes or other special symbols) or a regular expression.  Search
strings are not case-sensitive.

An example: Open the "BibTeX Example.bib" file.  Select "Search Fields",
and choose the "author" field.  Now enter the search string "Knuth".  The
results will be displayed in a new window -- command double-clicking on any
cite-key will send you to its original location.  Now search for the string
"Tcl|Tk" in the "titles" field to locate all entries with either Tcl or Tk
in their title.

Tip: holding down the shift key while command double-clicking on any text
will start a search for that text in the field in which it is contained in
the current window.

	Search All Bib Files

Search for a given string within all possible bibliographies.  This
item uses the list of bibliographies specified by the "Use ...  Path"
preferences available (as toggleable menu items) in the "BibTeX Files"
menu.  To find out which .bib files will actually be searched, use the
"BibTeX Files --> List All Bibliographies" menu item described below.  
Searches can be limited to specific fields, including cite-keys, or 
include the entire file (by specifying "all fields").

Unlike "Search Entries" and "Search Fields", strings are case-sensitive.

If searching for cite-keys, only a portion has to be entered, such as

    DiMagg

This search also supports of regular expressions, such as

    Marx|Engels

to locate bibliographies with citekeys including either "Marx" or "Engels". 
Or one could enter

    DiMag.+198

to find all of the bibliographies with 1980's DiMaggio entries (assuming
that you include the full century year in your citations.)  Or

    186[0-9]

to find all of bibliographies that contain 1860's citations.  

If only one file is identified, the results of the search will be inserted
automatically into a "Search Results" window.  If multiple files were
found, you will be given the option to list all of the search results in a
"browser" window (from which you can open any file), or to include only the
files that you specify.

You can interrupt this by hitting the Cmd-. key

	Quick Find Citation

(This is also bound to <control>-<shift>-Q for Alphatk users.)

Search the Index incrementally by cite key.  Requires that an index be
created, and if none exists you will be prompted to create one (based upon
the "Bib Auto Index" preference.)  The "List All Bibliographies" menu item
allows you to preview the files that will be indexed.  Indices and
Databases are described in more detail below.

Assuming that an index exists ...

The status bar window will prompt you for the first letter of the citation
that you want to find.  After typing it, you will be presented with a list
of all potential completions.  Pressing the tab key will extend the list. 
At this point you could either type the number of the item in list (as in
typing 2 for the second item you see presented) or press another letter to
reduce the options.  Once you have narrowed the selection to a single
unambiguous entry, you will jump to the citation you've chosen, opening the
file in which it is contained if necessary.


	  	 	Cite Key Lists


This menu helps you manage lists of cite-keys in both the open window and 
across multiple files.

	Count Entries

Report the total number of entries in the current window, as well the
number of entries of each type.

	Find Duplicates

Searches for duplicate cite-keys in the current window.  If any duplicates 
are found, results will be displayed in a new window -- command double 
clicking on any cite-key will take you to its original definition.  

Following a duplicate search, the cite-keys are saved by Alpha.  If you
perform subsequent duplicate cite-key searches on other windows, you will
be asked if you also want to compare these cite-keys to those of the
previous window.  (The file names of windows previously searched appears at
the bottom of this menu.)  If so, the cite-keys of this second window will
be added as well.  If not, the cite-key list will first be cleared.

Tip: Pressing the shift key while command double-clicking on any cite-key
will perform a rapid search for duplicates in the current window.

	List Cite Keys

This will create a new window that contains only the citation keys and the
"title" field of entries for easy scanning of the .bib files contents. 
Command double-clicking on any cite-key will return you to its original
entry.  Important: this is NOT the index used in "Quick Find Citation" or 
for electric completions.  See the "Indices and Databases" section below.

Indexing a "Search Results" window will give you a concise list of the 
entries that you have identified -- one possible use is to retrieve the 
list of entries found in the Marks menu.

	Count All Entries

(A dynamic menu item available by pressing the command key.)

Report the total number of entries in multiple files specified through a 
list-pick dialog.

	Find All Duplicates

(A dynamic menu item available by pressing the command key.)

This item allows you to easily compare the cite-keys of several files at 
once.  After choosing a list of files, the cite-keys of each one will be 
progressively added to the list and compared to those that are already 
there.  Results will be displayed in a new window.

Note that in both of these menu items the term "duplicate" is an exact one
-- after one match has been found, Alpha records the pair and moves on to
the next cite-key.  If a cite-key appears in three different files, it will
be noted as a duplicate for files 2 and 1, and then again (later in the
report) for files 3 and 1.  Before searching for duplicates across files, 
it is a good idea to check first for duplicates only within files.

	List All Cite Keys

(A dynamic menu item available by pressing the command key.)

Displays a list of all currently recognized cite-keys in a new window. 
This can be a slower procedure.  Command double-clicking on any listed
cite-key will take you to its original definition, opening the file if
necessary.  If no cite key list currently exists, you will be prompted to 
first create one.

	Create Cite Key List

Allows you to choose the files to include in the current cite-key list.  If
you only want to compare the current window against a list of others, first
create a list of the others.  (The files that are currently included in the
list appear at the bottom of this menu.  Selecting any of them will create
an "List Cite Keys" window using the menu item described above.)

Now select the "Find Duplicates" menu item.  When asked if you want to use 
the current list, choose "yes" and the cite-keys of the current window will 
be compared to the other files listed.

	Clear Cite Key List

Removes all current cite-keys from Alpha's memory.


	  	 	Sorting, Marking


	Sort by 
	---------

Sorts the current window by one of various criteria ...

The Overwrite Buffer preference controls whether the sorted database is
written back to the original buffer or into a new one.

	Cite Key

Sorts by the citation key

	First Author, Year

Sorts by first author, and secondarily by year

	Last Author, Year

Sorts by last author, and secondarily by year

	Year, First Author

Sorts by year, and secondarily by first author

	Year, Last Author

Sorts by year, and secondarily by last author


	Sort Marks 
	------------

Sorts the Marks either ...

	Alphabetically

Sorts the index marks on the marks menu alphabetically.

	By Position

Sorts the index marks by the position of the entry.

The {} "Parse Funcs" menu item will return only every 10th entry in the 
file, useful if you want to navigate a .bib file that has several hundred 
entries ...


	Bib File Conversions
	--------------------

A few conversion packages have been written for Alpha's Bib mode, to turn a
.bib file into a nicely formatted .html file, etc.  See the "Conversions"
section below for more information.


	  	 	Setting Bib Mode Options


This section contains four submenus which help you to configure Bib 
mode's various preferences and behavior.


	Default Entry Fields
	--------------------

This menu contains all of the entries in the "Entries" submenu.  By
default, only the required fields are included when a new bib entry is
created.  You can modify this behavior by selecting any one of these
entries -- a dialog box will present you with the current list.  Fields
will appear in the specified order.

These changes will be saved as a mode preference, and will remain in place
in future sessions of Alpha.

	Restore Default Preferences 

Allows you to restore any of the default entry preferences that you have
changed.

	Remove Custom Entry 

Allows you to remove any entries defined using the "Custom Entry" menu
item in the Entries menu.

	Edit Custom Fields 

Presents you with the option to add all of the "extra" fields found in the
current window to the "Add Fields" preference, inserting them into the
"Fields" menu and making them available for electric completions.  If this
option is not selected, you are presented with a list of the current "Add
Fields" preference, which you can then edit.


	BibTeX Mode Options
	-------------------

All of Bib mode's "flag" preferences can be turned on/off using the toggled
menu items.  These preferences are explained in more detail below.

Tip: Hold down any modifier key while selecting a mode option menu item to
obtain a brief description of the preference.

	BibTeX Mode Help

Opens this file ...


	Bib Mode Acronyms
	-----------------

Bib mode allows you to create acronyms for electric completion / expansion. 
Take the "Bib Tutorial.bib" completions tutorial for more information, or
see the section below on "Key Bindings and Completions".

This menu allows you to view, add, and remove the acronyms recognized by 
Bib mode.  In addition, you can "unset" the list of acronym expansions 
that are supplied by default.

	Check Keywords

If you are considering defining your own custom entry, field, or acronym,
it might be useful to first make sure that the keyword is not already
assigned in one of the mode's lists.

	Bib Mode Tutorial

Opens the "Bib Tutorial.bib" completions tutorial.


	Bib Mode Files
	--------------

This menu helps you set the behavior of Alpha regarding the creation of the
"bibliography file list".  This list, which is created "on the fly" when
needed by certain menu items or procedures, is used to create the indices
and databases described below, and for the "Search All Bib Files" menu
item.

	List All Bibliographies

Opens a dialog box, listing all of the bibliographies that would currently
be used to create a database or an index.  Double-clicking on any of these
files will open them in a new window.

	________________

The next four items are toggleable preferences that help determine how this
list is created.  (These are the same preferences that can be set in the
"Config --> Mode Prefs" dialog.)

	Full Pathnames

Include the full pathnames in list-pick dialogs and in the "BibTeX Files" 
menu.  Note that Bib mode is generally happier if no .bib files have the 
same filename -- if you have both

    :paper1/myfile.bib   and
    :paper2/myfile.bib

then command double-clicking in "Search Results" windows could get funky...

	Use Current Path

Look in the file folder of the current window for any valid .bib files.

	Use Open Windows

Include any open windows in the bibliography list, provided that they are
valid .bib files.

	Use Search Paths

Look in folders associated with both Bib or TeX modes, as set using the
"Set Search Paths" menu item.  Search paths (which are mode specific) only
have to be set for Bib or TeX modes -- when listing bibliographies Bib 
mode will use both.

	Use Tex Paths

Look in the Tex-inputs folder or .aux file to list all bibliographies. 
This only applies if you are prompted to rebuild an index or database in a
LaTeX document after failing to either complete a citation electrically, or
find a citation by command double-clicking on it .

The "TeX Path" is dependent on the .aux file of the current LaTeX document,
which cannot be accessed unless the "rebuild database" procedure is being
called by TeX mode.  These bibliographies could be included, however, via
the other preferences ...

	________________

The last section of this submenu allow one to set the "Search Paths"
specific to Bib mode.  These make use of the package: searchPaths, which
allows multiple folders to be designated for any mode.  (These menu items
are normally only available in the "Config --> Mode Prefs" menu, but are
reproduced here for convenience.  Activating the "Search Paths" package is 
not necessary.)

If the "Use Search Paths" preference is turned off, these items will be
dimmed -- just a little reminder that you need to set the preference AND
the search paths !


	  	 	Indices and Databases


The remaining items update (or create) the indices and databases used in
searching for and inserting BibTeX entries.  See the section above
regarding "BibTeX Files" to determine which files will be used in index or
database creation.

Indices and Databases support citation completions when editing LaTeX
files.  The term "database" properly suggests that this is a complete list
of the citation keys which you have instructed Alpha to keep track of.

For example, open a .bib file.  Select "Add Win to Database".  This indexes
all of the citation keys and titles in the current file and adds its path
to the search list.  Now open a .tex file.  Type

	\cite{<something>|

where <something> is the beginning of a reference key in .bib file you
just added to the citation database and attempt to complete it.  

(To find out what your completion key is, and to change it if desired, use
the "Config --> Special Keys" menu item.)

If the completion hint exists within the database, you should be prompted
with a list of completions (if the hint was ambiguous), or Alpha will
simply insert the citation key straight from the index or database. 
Command double clicking on the item will then open up the .bib file in
which it is contained.  If no completion can be found, you will be
presented with a list of various options -- including rebuilding the
index or database.

Bib Indices and Databases are very handy !!


	Build/Rebuild Index/Database

Builds (or rebuilds) the index/database, using the bibliographies file set
by the "Use ...  Paths" preferences.  

The "bibIndex" and "bibDatabase" files are stored in your prefs folder.

IMPORTANT: An Index only contains the cite keys, while a Database also
contains the titles.  TeX mode includes "Show Titles" preference that
determines what appears in the list-pick dialog when your attempted
completion is ambiguous -- just the citation keys (stored in a "bibIndex"
file), or both the keys and the titles (stored in a "bibDatabase" file.) 
The index is also used for the "Quick Find Citation" menu item.  


Rebuilding either the index or database will remove all previous
contents.  In practice, it's a good idea to rebuild both the index and
the database at the same time.

	Review Index/Database

(A dynamic menu item available by pressing the command key.)

Opens the "bibIndex/Database" file located in your preferences folder.  

	Remove Index/Database

(A dynamic menu item available by pressing the control key.)

Removes the "bibIndex/Database" file located in your preferences folder.
	

	Add Win To Index/Database

Adds the current open window to the bibliography index/database.  If the
current window is not a .bib file, you will have the option to choose
amongst all current open .bib windows.

Note that if this file had been previously added to the index/database,
the old entries are not removed.  You may do so yourself (manually) by
reviewing the index/database, unlocking it, and deleting the old
entries.  

	Add Files To Index/Database

(A dynamic menu item available by pressing the command key.)

Opens a list-pick dialog, allowing you to select files that will be
added to the bibliography index/database.  Only those files designated
by the "Use...  Path" preferences are available.  

Note that if these files had been previously added to the
index/database, the old entries are not removed.  You may do so yourself
(manually) by reviewing the index/database, unlocking it, and deleting
the old entries.


	======================================================================


	  	Mode Preferences


The behavior of the Bibtex menu may be controlled using by setting the
various preferences through the "Config --> Mode Prefs --> Preferences"
dialog.  Many of these can also be set using the "BibTeX Mode Options"
menu.  


	  	 	BibTeX Menu Options


	Hierarchical Menu

The appearance of the main BibTeX menu can be controlled by setting this
preference.  Turning it off will place the Navigation, Searching,
Formatting and Database items in the main menu.

	Short Bib Menu

Determines if the Search, Cite Key Lists, Bibtex Conversions, or Bib Mode
Acronyms will be included in the menu.  (If not, any key-bindings for the
items will still work.)  If this preference is turned off, Bib mode will 
load faster when it is first called.

	Database Menu Items

Determines if the "BibTeX File List", "Bib Mode Files" and "Database"
menus/menu items are included in the main Bib menu.  If this preference is
turned off, Bib mode will load faster when it is first called.

	Home Page

The url used by the "BibTeX Home Page" menu item.


	  	 	Completions, Electrics


	Field Completions

Allows fields to be completed when using electric routines.

	LaTeX Completions

Allows select LaTeX commands to be completed when using electric routines.

	Smart Dots

Turns '...'  into '\ldots' automatically as you type

	Smart Quotes

Turns ' or " into ` or `` or ' or '' automatically as you type, depending
upon the context.

	Unset Acronyms List

Allows you to remove the list of "default" acronyms provided by the mode. 
See the section below on "Key Bindings and Completions" for more
information.


	  	 	Entry Formatting, Validating


	Align Equals

Line up the = signs for all fields when reformatting.

	Entry Braces

Use curly braces to delimit entries (otherwise parentheses are used).

	Field Braces

Use curly braces to delimit field values (otherwise quotation marks are
used).

	Fill Column

The maximum width of each line in the field value.

	Ignore Extra Fields

Only report the missing required fields when validating entries.
Otherwise, all "non-standard" fields will be reported as well.

	Indent String

Define the indentation string for field names.  The default is three
spaces.

	Std Abbrevs

Define standard abbreviations (which we avoid surrounding with delimiters)
that do not appear in @string entries.

By default, three-letter English month names are included.

	Zap Empty Fields

Remove optional fields if they're empty.  All fields for entries defined
using the "Custom Entry" menu item are considered to be optional.


	  	 	Sorting, Marking


	Auto Mark

Automatically mark the .bib file when it is first opened, and following any
sorting routine.

	Descending Years

Sort by year in descending order (most recent to oldest).

	Mark Strings

Include @string definitions in the marks menu.

	Overwrite Buffer

Allow sorts to replace the original window contents -- otherwise they are
written to a new window.

	Segregate Strings

Collect all @string definitions together at the top of the file in sorts.
(Otherwise sort alphabetically)


	  	 	BibTeX Files


These items determine how the "bibliography list" is created, and are
described above in the "Indices and Databases" section.

	Full Pathnames

Include the full pathnames, not just the tail, in menus and dialogs.

	Build Files On Start

Automatically create the list of recognized .bib files when the Bib menu
is first created.


	Use Current Path

Look in the file folder of the current window for any valid .bib files.

	Use Open Windows

Include any open windows in the bibliography list, provided that they are
valid .bib files.

	Use Search Paths

Look in folders associated with Bib or TeX mode, depending on the mode of
the procedure which needs to create the list.

	Use Tex Paths

Look in the Tex-inputs folder or .aux file to list all bibliographies. 
This only applies if you are prompted to rebuild the database while editing
a LaTeX document.


	Bib Auto Index

When certain procedures determine that the Index / Database either doesn't 
exist or is out of date, they will attempt to rebuild them.  This 
preference allows you to be prompted before doing so.


	  	 	Keyword Colorizing


Colors can be defined for comments, strings, entries, and fields.  Special
LaTeX symbols ($ ^ _ ~ # and &) can also be colorized, useful when they are
contained in fields and must be preceded with a backslash.

Additional fields to be colorized can be included in the "Add Fields"
preference.

BibTeX mode supports colorizing and keyword completion of a limited number
of LaTeX commands, including all of those in the "LaTeX --> Text Style"
menu item.  Additional commands can be added in the "Add TeX Commands"
preference.  These will all use the Entry Color.


	======================================================================


	  	Key Bindings, Completions


Most of these functions (except template insertion) are also bound to
keystrokes.  The standard bindings are listed in the menu -- the usual
binding involves both control and shift.  Navigation menu items are also
bound to <control>-<shift>-<arrow keys>.

Although the TeX-mode keybindings aren't available in Bib mode, the LaTeX
menu can easily be inserted in the menubar.  This may be useful for
inserting the various text-style codes that are recognized in BibTeX
fields.  These are also available as electric completions -- see the 
completions tutorial "Bib Tutorial.bib" for more information.

While there are no key bindings for entry template insertion (such as @book,
@article,  etc), BibTeX mode has a built Electric Completion capabilities.

After typing in a portion of an entry, such as

	@art|

pressing your electric completion key will build the entry for you,
including your custom fields as you have defined them, such as

	@article{|,
	   author =   {},
	   title =    {},
	   journal =  {},
	   volume =   ,
	   number =   ,
	   pages =    {},
	   year =     ,
	   abstract = {},
	}

All defined fields, including those defined by the user, as well as defined
LaTeX commands can also be included in the completion routines, simply by
toggling the "Field / LaTeX Completions" menu items in the BibTeX Mode
Options menu.

User defined acronyms can also be completed or expanded.  For example, 
after typing

	ad|

and expanding it to

	address = {|},

one could type

	address = {ny|},

and expand it to

	address = {New York},

which means that all that you actually typed was

	ad|ny|

to insert the field.  Very efficient !!  Bib mode comes with a very small
demonstration set of acronyms, contained in "BibCompletions.tcl".  The menu
item "Bib Mode Acronyms --> Add Acronyms" allows you to create your own.

The Completions Tutorial ("Bib Tutorial.bib") contains more information
regarding completions and expansions.  This is available via the menu item
"Bib Mode Acronyms --> Bib Mode Tutorial" menu item.

The "Config --> Special Keys" menu item both tells you your electric
completion key and allows you to modify it.  For more information
concerning "electric" behavior, you could consult the "Alpha Manual" or the
more advanced "ElecCompletions Help" file.


	  	Command Double-Clicking


In Bib mode, command double clicking does different things depending on the
current window type and on the context of the text being selected.  (Note
that in this section "clicking" is means command double-clicking.)  In all
Alpha modes, command double-clicking is also bound to the F6 key.

	In .bib files ...

Clicking on cross-references and strings will move the cursor to the
location of their original entry.  Clicking on defined abbreviations will
confirm that they exist as a mode preference.  (Strings, cross-references 
and abbreviations are not surrounded by delimiters during reformatting.)

Clicking on an entry name (such as "article", "book", etc) will perform a 
quick validation check of required fields, displaying the results in the 
status bar window.

Clicking on a field name will format the entire entry.

Holding down the control key while command double-clicking on any text 
with a field will perform a search of that term across the entire window, 
displaying the results in a new window.

Similarly, holding down the shift key while clicking will search for that
term across the entire window, but limited to the field in which that term
is currently contained.  (For example, shift-clicking on "DiMaggio" in the
author field will display all entries where he is listed as an author.

	In Results windows ...

Clicking on cite-keys will bring the file in which they were defined to 
the front, opening the file if necessary.  (If the file is closed, Alpha 
relies on the "BibTeX Files" list to find it.)

	In View Bib Acronyms windows ...

Clicking on an acronym allows you to re-define it.


	  	Adding New Entries


Entries can be added to Bib mode's menu in two ways.  The first is to
simply use the "Entries --> Custom Entry" menu item.  This will prompt you
for the default fields for your new entry, and make it available as an
electric completion.  Use the "Default Entry Fields" menu to edit (or
remove) any custom entries.

Using this method will not, however, make the entry available for
validation, because none of its fields have been designated as either
"required" or "optional".  To teach Bib mode a new entry for validation
purposes, it should instead be defined in a "BibPrefs.tcl" file.  It should
include the following Tcl code:

	set   rqdFld(myEntry) "field1 field2 etc"
	set   optFld(myEntry) "field3 field4 etc"
	
	Bib::updateMyFld

Each line is important, and should be written exactly as it appears above.
Here's an example:

	set   rqdFld(webPage) "author url date"
	set   optFld(webPage) "organization"
	
	Bib::updateMyFld

In this case you would probably also want to add "url" and "date" to the
"Add Fields" preference.  Important: this means that "myEntry" should NOT
be defined using the "Custom Entry" menu item !!!  If it has already been
defined this way, the "Default Entry Fields --> Remove Custom Entry" menu
item will allow you to delete it.

After adding this code to the BibPrefs.tcl file, load the file using the
menu item "Mode Prefs --> Load Prefs File".  Your custom entry should then
be listed in the "Entries" menu, available as an electric completion, and
subject to field validation.  This file will be sourced automatically upon
every subsequent restart of Alpha.

(If you think that an additional entry should be included in the next Bib
mode distribution, be sure to send it to the mode's maintainer !)


	======================================================================


	  	Conversions


Alpha has a few BibTeX file conversion functions available in the
BibTeX menu, which are turned on by default.  They include:


	  	 	Bib To Html


Pierre Basso    <basso@lim.univ-mrs.fr>

package: bibToHtml

Bib To Html will convert either an entire bib file or only a selected
(highlighted) portion.  All the bib entries will be analyzed and converted
in a html bibliographic reference.  If you convert a file 'fooname.bib'
you'll get a file 'fooname.html' in the same folder.

When Bib To Html ends, it prompts the user to direct send the html file to
the browser, else it displays this file as a front window.  You may improve
this html file, in adding titles, figures or any fancies, for example,
before sending it to the browser.

Before this conversion the bib file can be sorted by the "Sort by" menu item.

Important: This procedure requires working on correct bib files, i.e.
devoid of any syntactical bibtex error.


	  	 	Bib To Refer (EndNote)


Peter Blattner    <peter.blattner@imt.unine.ch>

package: bibToRefer

Conversion of BibTeX to Refer (Endnote compatible).  If there are several
authors, each author has its own tag %A.

It might be necessary to run the "Convert LaTeX to Accent" utility first,
and eventually the "Format All Entries" menu item.

Important: "@string"s are not handled, and if they are present the
procedure will die without any warning.


	  	 	Bib Convert


Vince Darley    <vince@santafe.edu>

package: bibConvert

First attempt at parsing various records into bibtex entries.  It now copes
with hollis records, the horrible form of inspec record our firstsearch
interface gives us, and a nicer form of inspec record produced by another
interface.

Open a '.hollis' or '.inspec' file and Alpha automatically switches to
bibtex mode.  Select the bibtex menu item 'Bib Convert', also bound to the
key combination '<ctrl>-b', and Alpha converts the open window, saving it
in a new file (with extension '.bib'), which it then opens for you to
examine!

See also the notes contained in package: bibConvert and "bibConvert.tcl".

An example .hollis file, "Hollis-Example.hollis" is also included in the
Mode Examples folder.


	======================================================================


	  	BibTeX Application


You'll probably want either Vince's Macintosh port of BibTeX (available
with OzTeX, or at <http://www.santafe.edu/~vince>) which allows a lot of
cool command-clicking in a log window to leap to errors/warnings in your
.bib files, or you may want to use the version with CMacTeX (shareware).

The original Unix version is by Oren Patashnik: BibTeX 0.99c .


If you are using a Macintosh BibTeX application, then you should take
advantage of the package: bibtexEngine, a global feature.

As Vince describes it:

When you command click on warnings, errors and filenames in the BibTeX log
window, BibTeX sends a particular kind of apple-event to your 'bibresult'
helper application.  This file contains procedures for the editor Alpha
which allows it to receive and interpret those messages in a useful way.
It's a huge time-saver, I guarantee!

To use this feature, you must also open Internet Config, select 'helpers'
and add a helper for 'bibresult', and select as helper the application
'Alpha'.

For the technically minded: I use Internet Config to do the dirty work
of sending apple-events for me.  One day I'll write my own code, but this
hack works quite well for the moment.)


	  	BibTeX Mode History


This package was inspired by LaTeX support package (latex.tcl), written by

    Tom Scavo          <trscavo@syr.edu>  , and (originally),
    Richard T. Austin  <austin@eecs.umich.edu>

The Bib mode was originally written by Tom Pollard in 1994.  Vince Darley
reworked the mode from 1997 to 1999.  Further suggestions were incorporated
by Craig Barton Upright in 2000 -- Vince said that the mode was currently
homeless, and Craig offered to be the mode's maintainer until someone else
steps forward.

The "bibVersionHistory.tcl" file contains a more complete version history.


	  	Future Directions


Bug reports, complaints and suggestions are very welcome.  Most of the
improvements and bug fixes made since the last major release (2.0) were
the result of reports and suggestions from users.

Version 3.6 introduced a lot of changes, and there are sure to be a few
bugs somewhere.  Reports should be directed to the current maintainer:

         Craig Barton Upright  <cupright@princeton.edu>

or submitted to the ALPHA-D mailing list.

These are some of the ideas that Vince is considering for future enhancements
to the BibTeX support package (roughly in the order they are likely to be
addressed).  We welcome any comments or additional ideas people may have.

1.  Speed up entry reformatting.  (Not as troubling with the newer Macs,
    and should be considerably faster in Alpha 8.)

2.  Allowing more complicated searches.  Logical 'AND' searches can be
    done now by doing additional searches on the results of previous ones.
    It would be nice to allow logical 'OR' searches by concatenating the
    results of successive searches to a database in the same buffer.  Ideas
    for simple, intuitive ways to control this would be welcome.

    (Note -- I've changed the behavior of "Search Results"  since Vince
    wrote this.  Do the current options meet users' needs ??  -- cbu )

3.  Since the code parses BibTeX entries already, it would be easy to
    export .bib files to other formats beyond Refer and Html, but I'm not
    sure if it's a good idea to start burdening Alpha with that sort of
    thing.  Writing Perl scripts for file conversions is probably a better
    idea.  See, for instance, the CC to BibTeX Perl script (included in the
    :Tcl:Packages:Text Filters folder), which converts citations from the
    on-line Current Contents database (the one at UC Berkeley, anyway) to
    BibTeX format.

Craig's list:

1.  It would be nice to somehow recognize remote files in the Bib Files
    list.  I can imagine a preference for "Use Remote Paths", and then some
    menu items similar to mode search paths to select them.  This should
    probably be incorporated into the package: modeSearchPaths, rather than
    being specific Bib mode procedures.  If this were added, I would
    probably set the preference to "0" every time the mode is initially
    loaded so that we don't call the ftp helper unless we make a conscious
    decision.  

    (Selecting the preference in the "Bib Mode Files" menu would then call
    the helper, and rebuild the list -- the actual paths would be saved
    between sessions.)

2.  The current manipulation and storage of cite key lists probably isn't
    so very efficient, and perhaps they should simply be stored in a cache
    somewhere.  The current solutions work, but slow down considerably
    when the list gets very large (say more than 750 entries or so.)


	  	License and Disclaimer


Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

  Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

  Neither the name of Alpha/Alphatk nor the names of its contributors may
   be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.

This mode is free.  Alpha is shareware ! <<register>>


cheers,

-- Craig


Help Authors:  Tom Pollard, Vince Darley, Craig Barton Upright

   Maintainer:  Craig Barton Upright
       E-mail:  <cupright@princeton.edu>
         mail:  Princeton University,  Department of Sociology
                Princeton, New Jersey  08544
          www:  <http://www.princeton.edu/~cupright/>
